Devices > Remote Devices > IoT Sparkplug EIE > Device Template Properties

IoT Sparkplug EIE Device Template Properties

The IoT Sparkplug EIE sample device template file includes unique data group elements and attributes and may include a section specific to this EIE. This topic contains an example of an IoT Sparkplug device template file.

Device Template Elements and Attributes for the IoT Sparkplug EIE

Sparkplug defines a standard mechanism for formatting payload data, so very little customization is provided for in the template file. The only customization allowed provides a mapping from payload text strings representing data units to CygNet units.

Payload Definition

The payloadDef section of an IoT Sparkplug EIE device template file contains information to allow users to interpret payload data for CygNet. This section is optional.

Element Description

mapUnits

Maps units in the payload to CygNet units. This section is needed only when the payload indicates data units that you want to import into CygNet.

For example, CygNet represents kilograms as "kg", while a payload may use the text "KGRAM". This section of the template file can be used to map the text string "KGRAM" from the payload to "kg" in CygNet.

ex

Each enumeration must begin with a lowercase e. It is then to be followed by a "units" text string as defined in the payload (e.g., units "KGRAM" in the payload is represented as eKGRAM.)

Each enumeration element must be unique, but its value does not need to be unique. For example, using eKGRAM twice within a single enumeration list is illegal, but using the value "kg" for eKGRAM and eKILOGRAM is legal.

Each enumeration must use a value attribute to define a constant value that corresponds to a valid CygNet unit. See PNT Engineering Units.

Device Definition Attributes

The following table lists and describes IoT Sparkplug-specific device definition attributes.

Attribute Description

class

Set to "POC" if the payload represents a pump-off controller and includes dynagraph cards. Otherwise the attribute should be omitted.

Data Group Attributes

The following table lists and describes IoT Sparkplug-specific data group attributes.

Attribute Description

setUnreliableOnLostConnection

If this value is set to "true", all CygNet points will be set to unreliable upon receipt of a DEATH message for the topic associated with the data group. A DEATH message is issued when the MQTT server loses the connection to the remote device or node.

uccRecv

Set to "true" to allow a rebirth request to be issued via UIS command.

canRecv

Set to "true" to allow a rebirth request to be issued from CygNet Explorer.

Data Group Elements

The following table lists and describes IoT Sparkplug-specific data group elements. These items are identified in the Sparkplug specification, but are optional and may not appear in all payload files.

Data Group Element ID Description

_topicSeq

The topic/payload sequence number.

_topicUuid

The topic/payload UUID.

_topicTime

The topic/payload data time. This value is used for point processing in the absence of a timestamp associated with each payload item.

Data Group Element Attributes

The following table lists and describes IoT Sparkplug-specific attributes of data group elements.

Attribute Description

itemId

The name of the item in the payload file. This is used to map an item in a payload file to a CygNet data group element. It is not used for data group elements _topicSeq, _topicUuid, or _topicTime, which are predefined in the Sparkplug specification.

The itemId allows the following substitution strings :

  • %deviceId%
  • %facilityId%
  • %ordinal%

type

It is recommended that type variant ("vrnt") be used to preserve the data type provided in the payload.

IoTSparkplug_Sample.dtf

The IoTSparkplug_Sample device template file includes data that defines what the Sparkplug payload looks like and where to find specific items in the payload. For more information about the Sparkplug specification, see the Sparkplug Specification document.

The following example displays the IoTSparkplug_Sample.dtf.

Example

ClosedClick here to see an example of the template

 

<deviceDefinition deviceType="IoTSparkplugSample" mfg="CygNet" desc="IoT Sparkplug Sample" category="4098" model="Generic" eieType="IoTSparkplug" cygnetVersion="9.2.1000" customerVersion="">

<dataGroups udcCat="UDCALL" canSend="false" canRecv="false" uccSend="false" uccRecv="false" udcDefFac="true" baseOrd="0" devDG="false" maxCnt="1" forceSave="true" setUnreliableOnLostConnection="true">>

<Topic1 niceName="Topic 1">

<dgElements secLev="4" type="vrnt">

<_topicSeq desc="Seq #"/>

<_topicUuid desc="UUID"/>

<_topicTime desc="Date/time (#)" hidden="true"/>

<_topicTs desc="Date/time" ref="_topicTime" type="string" format="DateTime"/>

<SignedI1 desc="Signed byte" itemId="sbyte1"/>

<SignedI2 desc="Signed word" itemId="sword1"/>

<SignedI4 desc="Signed double word (scaled)" itemId="sdword1" cvtF="Scale" sourceType="i4" type="r4" scaleFactor=".01" units="in"/>

<SignedI8 desc="Signed quad word" itemId="sqword1"/>

<Unsigned1 desc="Unsigned byte" itemId="ubyte1"/>

<Unsigned2 desc="Unsigned short word" itemId="uword1"/>

<Unsigned4 desc="Unsigned double word" itemId="udword1"/>

<Unsigned8 desc="Unsigned quad word" itemId="uqword1"/>

<Float desc="Float" itemId="float1"/>

<Double desc="Double" itemId="double1"/>

<Bool desc="Boolean" itemId="boolean1"/>

<String desc="String" itemId="string1"/>

</dgElements>

</Topic1>

</dataGroups>

<defDataGroups/>

<defUisCmds visible="true" canBeScheduled="true" clientCanInvoke="true" inheritsSecurity="false"/>

</deviceDefinition>

IoTSparkplug_POC.dtf

The IoTSparkplug_POC sample device template file includes the "Dynagraph Card" (DynaCard) data group. This device represents a pump-off controller, so the device class is identified as "POC" and the template file includes a "Dynagraph Card" (DynaCard) data group. The "Dynagraph Card" data group includes data group elements only to support point processing. If point processing is not desired, they can be omitted.

The following example displays a section of the IoTSparkplug_POC.dtf. Note the attribute class="POC" in the deviceDefinition section.

For more information, see IoT Sparkplug EIE Dynagraph Data Group.

Example

ClosedClick here to see an example of the template

 

<deviceDefinition deviceType="IoTSparkplugPOC" mfg="CygNet" desc="IoT Sparkplug POC" category="4098" model="Generic" eieType="IoTSparkplug"class="POC" cygnetVersion="9.3.1000" customerVersion="">

<dataGroups udcCat="UDCALL" canSend="false" canRecv="false" uccSend="false" uccRecv="false" udcDefFac="true" baseOrd="0" devDG="false" maxCnt="1" forceSave="true" setUnreliableOnLostConnection="true">>

<DynaCard niceName="Dynagraph Card" dgCat="internal" maxCnt="8">

<dgElements secLev="4" type="vrnt">

<SCnt desc="Surface point count"/>

<SLMin desc="Surface min load"/>

<SLMax desc="Surface max load"/>

<DCnt desc="Downhole point count"/>

<DLMin desc="Downhole min load"/>

<DLMax desc="Downhole max load"/>

<HrGgeOff desc="Hours since gauge off" units="hour"/>

<StrkPeriod desc="Stroke period (secs/stroke)"/>

<PumpSpeed desc="Pump speed (SPM)"/>

<StrokeLen desc="Stroke length" units="in"/>

</dgElements>

</DynaCard>
Back to top

Let us know how we can improve this topic.

CygNet at weatherford.com

© 2020 Weatherford. All rights reserved.